{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Libraries\n",
    "\n",
    "**Time**\n",
    "- Teaching: 5 min\n",
    "- Exercises: 5 min\n",
    "\n",
    "**Questions**:\n",
    "- \"How can I use software that other people have written?\"\n",
    "- \"How can I find out what that software does?\"\n",
    "\n",
    "**Learning Objectives**:\n",
    "- \"Explain what software libraries are and why programmers create and use them.\"\n",
    "- \"Write programs that [import](https://github.com/dlab-berkeley/python-intensive/blob/master/Glossary.md#import) and use libraries from Python's standard library.\"\n",
    "- \"Find and read [documentation](https://github.com/dlab-berkeley/python-intensive/blob/master/Glossary.md#documentation) for standard libraries interactively (in the interpreter) and online.\"\n",
    "\n",
    "*****\n",
    "\n",
    "## Most of the power of a programming language is in its libraries.\n",
    "\n",
    "*   A *library* is a collection of functions that can be used by other programs.\n",
    "    *   May also contain data values (e.g., numerical constants).\n",
    "    *   Library's contents are supposed to be related, but there's no way to enforce that.\n",
    "*   Python's [standard library](https://docs.python.org/3/library/) is installed with it.\n",
    "*   Many additional libraries are available from [PyPI](https://pypi.python.org/pypi) (the Python Package Index).\n",
    "*   We will see later how to write new libraries.\n",
    "\n",
    "## A program must import a library in order to use it.\n",
    "\n",
    "*   Use `import` to load a library into a program's memory.\n",
    "*   Then refer to things from the library as `library_name.thing_name`.\n",
    "    *   Python uses `.` to mean \"part of\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "print('pi is', math.pi)\n",
    "print('cos(pi) is', math.cos(math.pi))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*   Have to refer to each item with the library's name.\n",
    "    *   `math.cos(pi)` won't work: the reference to `pi` doesn't somewhow \"inherit\" the function's reference to `math`.\n",
    "\n",
    "## Use `help` to find out more about a library's contents.\n",
    "\n",
    "*   Works just like help for a function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(math)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import specific items from a library to shorten programs.\n",
    "\n",
    "*   Use `from...import...` to load only specific items from a library.\n",
    "*   Then refer to them directly without the library name as prefix.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from math import cos, pi\n",
    "\n",
    "print('cos(pi) is', cos(pi))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create an alias for a library when importing it to shorten programs.\n",
    "\n",
    "*   Use `import...as...` to give a library a short *alias* while importing it.\n",
    "*   Then refer to items in the library using that shortened name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math as m\n",
    "\n",
    "print('cos(pi) is', m.cos(m.pi))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*   Commonly used for libraries that are frequently used or have long names.\n",
    "    *   E.g., `matplotlib` plotting library is often aliased as `mpl`.\n",
    "*   But can make programs harder to understand,\n",
    "    since readers must learn your program's aliases."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing a library with Anaconda Navigator\n",
    "\n",
    "Many popular (and some not-so-popular) libraries are available for installation through the Anaconda Navigator. Let's use the Anaconda Navigator to install a library called `fuzzywuzzy`. \n",
    "\n",
    "To do so, follow these steps:\n",
    "\n",
    "1. Open the Anaconda Navigator application\n",
    "2. Click the \"Environments\" tab in the left-hand menu\n",
    "3. Click the drop-down box that, by default, says \"Installed\". Change it to say \"All\".\n",
    "4. Click the \"Channels\" button, which will open up a dialog box. In that dialog box press the \"Add\" button in the top right corner. Type \"conda-forge\" in the new line that appears in the dialog box, then press enter. Finally press the green \"Update channels\" button in the bottom right-hand corner.\n",
    "5. Use the \"Search Package\" text box to enter \"fuzzywuzzy\" and press enter.\n",
    "6. Select the checkbox next to the fuzzywuzzy package (library) name that appears in the list below.\n",
    "7. Click the green \"Apply\" button in the bottom right-hand corner. This will open up a dialog box that says \"Install Packages\". It will say \"Solving package specifications\" with a blue progress bar. This may take a few minutes.\n",
    "8. Eventually it will show a list of packages that would need to be installed. If everything looks ok to you, press the green \"Apply\" button in the \"Install Packages dialog box\" which will install the packages. This may take a few minutes too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fuzzywuzzy import fuzz\n",
    "\n",
    "print(fuzz.ratio(\"Rochelle\", \"Rochele\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge 1: Locating the Right Library\n",
    "\n",
    "You want to select a random value from your data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    " ids = [1, 2, 3, 4, 5, 6]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. What [standard library][stdlib]    would you most expect to help?\n",
    "2. Which function would you select from that library? Are there alternatives?\n",
    "\n",
    "[pypi]: https://pypi.python.org/pypi/\n",
    "[stdlib]: https://docs.python.org/3/library/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge 2: Exploring the Math Library\n",
    "\n",
    " 1. What function from the `math` library can you use to calculate a square root\n",
    "    *without* using `sqrt`?\n",
    " 2. Since the library contains this function, why does `sqrt` exist?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge 3: When Is Help Available?\n",
    "\n",
    "When a colleague of yours types `help(math)`,\n",
    "Python reports an error:\n",
    "\n",
    "> ~~~\n",
    "> NameError: name 'math' is not defined\n",
    "> ~~~\n",
    "\n",
    "What has your colleague forgotten to do?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge 4:  Importing With Aliases\n",
    "\n",
    "1. Fill in the blanks so that the program below prints `90.0`.\n",
    "2. Rewrite the program so that it uses `import` *without* `as`.\n",
    "3. Which form do you find easier to read?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math as m\n",
    "angle = ____.degrees(____.pi / 2)\n",
    "print(____)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge 5: Importing Everything\n",
    "\n",
    "We can uses the `*` character to import everything from a library, and then refer to each item by name without a prefix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from math import *\n",
    "print(pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why would't programmers always use this form of import?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## [OPTIONAL] Installing a library with `pip`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While the Anaconda distribution comes with many additional libraries beyond the standard, it may happen that you find a library online that isn't yet installed on your computer. Most of the time, this library will be available in [PyPI](https://pypi.python.org/pypi) (the Python Package Index).\n",
    "\n",
    "To install from PyPI, simply open a terminal/shell window and type:\n",
    "\n",
    "`pip install \"name of package\"`\n",
    "\n",
    "Let's install a popular fuzzy matching library by typing:\n",
    "\n",
    "`pip install fuzzywuzzy`\n",
    "\n",
    "Once installed, we can import the library and use the `fuzz.ratio` method to compare two strings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fuzzywuzzy import fuzz\n",
    "\n",
    "print(fuzz.ratio(\"Rochelle\", \"Rochele\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "*****\n",
    "## Keypoints\n",
    "\n",
    "- \"Most of the power of a programming language is in its libraries.\"\n",
    "- \"A program must import a [library](https://github.com/dlab-berkeley/python-intensive/blob/master/Glossary.md#library) in order to use it.\"\n",
    "- \"Use `help` to find out more about a library's contents.\"\n",
    "- \"Import specific items from a library to shorten programs.\"\n",
    "- \"Create an alias for a library when importing it to shorten programs.\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.2"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
